package org.fujay.langchain4jserver.domain.knowledge.service;

import org.fujay.commons.langchain4j.rag.processor.result.DocumentProcessResult;
import org.fujay.langchain4jserver.domain.knowledge.vo.FileId;
import org.fujay.langchain4jserver.domain.knowledge.vo.KnowledgeBaseId;

/**
 * 知识库索引领域服务接口 定义了与索引相关的各种操作。 实现类通常需要处理异步逻辑 (@Async)。
 */
public interface IndexingService {

    /**
     * 异步处理单个文件的索引。 包括文档加载、切分、向量化和存储。
     *
     * @param fileId 要处理的文件 ID
     * @return
     */
    DocumentProcessResult indexFile(FileId fileId);

    /**
     * 异步处理整个知识库的索引。 遍历知识库下所有状态为 PENDING 或 FAILED 的文件进行索引。
     *
     * @param knowledgeBaseId 要处理的知识库 ID
     */
    void indexKnowledgeBase(KnowledgeBaseId knowledgeBaseId);

    /**
     * 异步重建知识库索引。 可能包括清空现有索引，然后重新索引所有文件。
     *
     * @param knowledgeBaseId 要重建索引的知识库 ID
     */
    void rebuildIndex(KnowledgeBaseId knowledgeBaseId);

    /**
     * 删除指定知识库的整个向量索引。
     *
     * @param knowledgeBaseId
     */
    void deleteKnowledgeBaseIndex(KnowledgeBaseId knowledgeBaseId);

    /**
     * 从向量索引中删除与特定文件关联的所有文档段（Segments/Embeddings）。
     *
     * @param knowledgeBaseId
     * @param fileId          要删除文档段的文件 ID
     */
    void deleteDocumentSegments(KnowledgeBaseId knowledgeBaseId, FileId fileId);
}
